Improve visualizer usability #1382

wenli-cai · 2025-07-24T18:00:23Z

Currently

Color code each Node in this frame based on its events, i.e. it was a new node, its states were changed, nothing changed but a child was changed. Also provides a color legend on hover of each node.
Improve node detail panel UI
Change tree UI to hide unaffected children
Allow file dump after live tracing
Show text diff for nodes' states
Allow device selection for live mode
Change selector style for selecting frames

Using reflection gives us the declared fields of a class only in alphabetical order, and some information is unnecessarily inside, so we instead just manually give back a list and the data associated with them through companion methods.

The only important fields of a node is its state, props, and rendering. Its and the parent node's ID's are less significant, and have been moved out of their own detailed cards to avoid cluttering up the info panel

All simple nodes (with no children) are shown at the top and nested nodes (with children) are shown at the bottom. This makes it the nesting more clear.

wenli-cai · 2025-07-26T18:13:44Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/util/DiffUtils.kt

+    builder.pushStyle(style)
+    builder.append(text)
+    builder.pop()
+  }


Having a helper function like this makes it very easy to understand what these three lines are doing, but having to list out the arguments (line 38 vs 43) ends up taking 5 lines instead of 3. Is this a worth it trade off?

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

zach-klippenstein · 2025-08-14T00:01:14Z

workflow-core/dependencies/jvmMainRuntimeClasspath.txt

-org.jetbrains.kotlin:kotlin-bom:2.1.21
-org.jetbrains.kotlin:kotlin-stdlib-common:2.1.21
-org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.1.21
-org.jetbrains.kotlin:kotlin-stdlib-jdk8:2.1.21
-org.jetbrains.kotlin:kotlin-stdlib:2.1.21
-org.jetbrains.kotlinx:kotlinx-coroutines-bom:1.7.3
-org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.7.3
-org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3
+org.jetbrains.kotlin:kotlin-bom:2.2.0
+org.jetbrains.kotlin:kotlin-stdlib-common:2.2.0
+org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.0
+org.jetbrains.kotlin:kotlin-stdlib-jdk8:2.2.0
+org.jetbrains.kotlin:kotlin-stdlib:2.2.0
+org.jetbrains.kotlinx:kotlinx-coroutines-bom:1.9.0
+org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.9.0
+org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0


I don't think we can update these dependencies to 2.2.0 until Register is on it. At any rate, it's better to do major dependency updates separately from feature changes.

Yeah I missed some things when reverting the dependencies, fixed.

zach-klippenstein · 2025-08-14T00:02:28Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/App.kt

+    modifier = modifier.onGloballyPositioned {
+      appWindowSize = it.size
+    }


When you only need the size, use onSizeChanged. onGloballyPositioned is very expensive. More here.

zach-klippenstein · 2025-08-14T00:05:52Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/App.kt

  var frameIndex by remember { mutableIntStateOf(0) }
  val sandboxState = remember { SandboxState() }
+  val nodeLocations = remember { mutableListOf<SnapshotStateMap<Node, Offset>>() }


nodeLocations is read in composition, so it needs to be snapshot state backed.

Suggested change

val nodeLocations = remember { mutableListOf<SnapshotStateMap<Node, Offset>>() }

val nodeLocations = remember { mutableStateListOf<SnapshotStateMap<Node, Offset>>() }

Hm, the original goal was that I would only want compositions to track what's happening to each SnapshotStateMap since that's where all the locations are stored, and I would just index into the list. Would my current code not work for that?

No, because when you clear (line 79) or put a new entry in the list (line 100), line 114 needs to know about it since the presence of that index in the list might change.

It's fine to keep the SnapshotStateMap as well though so you invalidate the map without invalidating the list. Nested state collections are fine.

ah okay, that makes a lot of sense. Fixed

zach-klippenstein · 2025-08-14T00:06:19Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/App.kt

+    ) {
+      if (active) {
+        // Since we can jump from frame to frame, we fill in the map during each recomposition
+        if (nodeLocations.getOrNull(frameInd) == null) {


Suggested change

if (nodeLocations.getOrNull(frameInd) == null) {

if (nodeLocations[frameInd] == null) {

I think using square brackets to index could throw an IndexOutOfBoundsException right? Having .getOrNull was for the purpose when we go from frame 0 immediately to frame 10, so we would need to fill in the gap of frames with empty maps.

That's easy to miss, might be nice to add a comment about that intention.

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/App.kt

zach-klippenstein · 2025-08-14T00:21:52Z

...w-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/control/SearchBox.kt

+  ) {
+    val relevantNodes = nodes.filter { it.name.contains(searchText, ignoreCase = true) }
+    Column {
+      relevantNodes.take(5).forEach { node ->


...trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/util/SandboxBackground.kt

...-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/util/parser/DiffUtils.kt

...race-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/util/parser/TraceParser.kt

steve-the-edwards

Resolve the Compose questions/comments from @zach-klippenstein and let's change the example .gifs to a dummy app , but otherwise LGTM.

steve-the-edwards · 2025-08-15T15:34:58Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/model/NodeUpdate.kt

+  NEW(Color(0x804CAF50)), // green
+  STATE_CHANGED(Color(0xFFE57373)), // red
+  PROPS_CHANGED(Color(0xFFFF8A65)), // orange
+  CHILDREN_CHANGED(Color(0x802196F3)), // blue


I think we just call this "RENDERED" or something like that?
When PTR is on then this will represent "Children Changed", but otherwise, that's not always true as all nodes will be rendered.

steve-the-edwards · 2025-08-15T15:36:02Z

...w-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/WorkflowInfoPanel.kt

@@ -55,6 +58,9 @@ internal fun RightInfoPanel(
    IconButton(
      onClick = { panelOpen = !panelOpen },
      modifier = Modifier
+        .size(40.dp)
+        .clip(CircleShape)
+        .background(Color.White)
        .padding(8.dp)
        .size(40.dp)


size specified twice? Does order matter?

Nope! Removed one now

steve-the-edwards · 2025-08-15T15:36:44Z

...w-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/WorkflowInfoPanel.kt

+        text = "${node.current.parent} (ID: ${node.current.parentId})",
+        style = MaterialTheme.typography.subtitle2,
+        color = Color.Gray,
+        modifier = Modifier.padding(top = 8.dp)


We should extract constants/styles for these padding values etc.

(If that needs to be done separately/later, that's fine too!)

This would all be the kind of stuff that goes in resources? I may not have time to pull out all the styles.

I wouldn't use Android resources for it, if that's what you mean. Just kotlin constants.

steve-the-edwards · 2025-08-15T15:46:39Z

...ce-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/control/DisplayDevices.kt

+              emulatorRegex.find(device)?.value?.let { emulator ->
+                onDeviceSelect(emulator)
+              }


DOn't we only want to show this card if we find the emulator? Othrewise its a noop.

What do you mean by "find" the emulator? I have a early return above if that's what you're asking?

steve-the-edwards · 2025-08-15T15:47:11Z

...ow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/control/FileDump.kt

+    }
+  ) {
+    val text = if (clicked) {
+      "Trace saved to Downloads"


would be great to show the filepath here.

zach-klippenstein · 2025-08-15T17:42:45Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/App.kt

  var frameIndex by remember { mutableIntStateOf(0) }
  val sandboxState = remember { SandboxState() }
+  val nodeLocations = remember { mutableListOf<SnapshotStateMap<Node, Offset>>() }


No, because when you clear (line 79) or put a new entry in the list (line 100), line 114 needs to know about it since the presence of that index in the list might change.

It's fine to keep the SnapshotStateMap as well though so you invalidate the map without invalidating the list. Nested state collections are fine.

zach-klippenstein · 2025-08-15T17:44:41Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/WorkflowTree.kt

-         */
-        node.children.forEach { (index, childNode) ->
-          val prevChildNode = previousNode?.children?.get(index)
+        nestedChildren.forEach { childNode ->
          DrawTree(


when a new frame is selected, but that would mean the composable is thrown out and restarted right?

I don't know, it would be if the composable that renders the frame is keyed on the frame. Either way though, sounds like this is fine.

zach-klippenstein · 2025-08-15T17:45:49Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/WorkflowTree.kt

+  )
+
+  Box {
+    Box(


If I'm reading it correctly, the structure is:

Box { Box { Column } Tooltip }

You only need the outer box to layer the column and the tooltip, the inner box only wraps the column and can be eliminated.

zach-klippenstein · 2025-08-15T17:47:57Z

...w-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/WorkflowInfoPanel.kt

+        text = "${node.current.parent} (ID: ${node.current.parentId})",
+        style = MaterialTheme.typography.subtitle2,
+        color = Color.Gray,
+        modifier = Modifier.padding(top = 8.dp)


I wouldn't use Android resources for it, if that's what you mean. Just kotlin constants.

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

wenli-cai added 10 commits July 21, 2025 16:45

Complete reset when changing trace files

e3b81f3

Fix naming for node current and past state

cbcea20

Enumerate the specific changes for each node and color them accordingly

9c1fc6a

Change node data being visualized

1ce9943

The only important fields of a node is its state, props, and rendering. Its and the parent node's ID's are less significant, and have been moved out of their own detailed cards to avoid cluttering up the info panel

Remove unnecessary frame tracking in main composable

b5d3b16

Add legend for the colors used in the frame

6dddf94

Group unaffected and affected children separately

6d2d31b

Separate composable components and change workflow UI pattern

e71a870

All simple nodes (with no children) are shown at the top and nested nodes (with children) are shown at the bottom. This makes it the nesting more clear.

Don't apply simple/nested pattern for unaffected children group

18c3b6f

wenli-cai changed the title ~~Wenli/improve visualizer~~ WIP improve visualizer usability Jul 24, 2025

Base automatically changed from wenli/visualizer-uds to main July 25, 2025 02:43

wenli-cai and others added 6 commits July 26, 2025 14:07

Add file dump functionality from live tracing mode

5646d10

Fix NPE when enabling live view without a connected device

18f82cd

Enable compose hot reload

07ab5fd

Change sample/tutorial module's agp version

58c58a9

WIP text diff

2aaa120

Add text-diff functionality

5ec8a18

wenli-cai force-pushed the wenli/improve-visualizer branch from e73317b to 5ec8a18 Compare July 26, 2025 18:07

Fix compose violations

82eae8b

wenli-cai commented Jul 26, 2025

View reviewed changes

wenli-cai and others added 7 commits July 26, 2025 14:29

Merge branch 'main' into wenli/improve-visualizer

1633f4c

Apply changes from dependencyGuardBaseline --refresh-dependencies

1e1da90

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Apply changes from artifactsDump

8fbeab4

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Fix merge bugs

a50f9a5

Allow device selection

c4fe05e

Manual api dump

6687f04

Remove compose hot reload changes

cdfbc82

wenli-cai force-pushed the wenli/improve-visualizer branch from bb01fc9 to cdfbc82 Compare July 28, 2025 15:28

Apply changes from dependencyGuardBaseline --refresh-dependencies

5d3e3f4

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

wenli-cai added 2 commits August 4, 2025 16:47

New frame selector format

418abf1

Fill background of info panel arrow

f2b5169

wenli-cai force-pushed the wenli/improve-visualizer branch 2 times, most recently from 59d285a to ff128a8 Compare August 5, 2025 19:06

Usage guide gifs

7b7b41a

wenli-cai force-pushed the wenli/improve-visualizer branch from ff128a8 to 7b7b41a Compare August 5, 2025 19:14

Improve readme

a489f00

wenli-cai force-pushed the wenli/improve-visualizer branch from 8745914 to a489f00 Compare August 5, 2025 19:20

Fix reset state

03c505d

wenli-cai marked this pull request as ready for review August 12, 2025 20:24

wenli-cai requested review from zach-klippenstein and a team as code owners August 12, 2025 20:24

Cleanup code for review

08f412c

wenli-cai force-pushed the wenli/improve-visualizer branch from 83502fe to 08f412c Compare August 12, 2025 20:49

wenli-cai changed the title ~~WIP improve visualizer usability~~ Improve visualizer usability Aug 14, 2025

zach-klippenstein requested changes Aug 14, 2025

View reviewed changes

wenli-cai added 2 commits August 14, 2025 10:35

Revert dependencies classpath

543258b

Add remaining internal modifiers

4a8d29d

wenli-cai force-pushed the wenli/improve-visualizer branch from cfa0bd8 to 4a8d29d Compare August 14, 2025 14:38

Fix PR comments

6a056ca

wenli-cai force-pushed the wenli/improve-visualizer branch from ea48f89 to 6a056ca Compare August 15, 2025 15:39

steve-the-edwards approved these changes Aug 15, 2025

View reviewed changes

wenli-cai force-pushed the wenli/improve-visualizer branch from 7520167 to 54e15a3 Compare August 15, 2025 17:14

zach-klippenstein approved these changes Aug 15, 2025

View reviewed changes

wenli-cai force-pushed the wenli/improve-visualizer branch 2 times, most recently from 4f79fb8 to 74fdadf Compare August 15, 2025 18:40

Fix more PR comments

d3645e1

wenli-cai force-pushed the wenli/improve-visualizer branch from 21b7902 to d3645e1 Compare August 15, 2025 18:59

wenli-cai and others added 2 commits August 15, 2025 15:13

Merge branch 'main' into wenli/improve-visualizer

4a6ca5b

Apply changes from apiDump

989766d

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

	val nodeLocations = remember { mutableListOf<SnapshotStateMap<Node, Offset>>() }
	val nodeLocations = remember { mutableStateListOf<SnapshotStateMap<Node, Offset>>() }

	if (nodeLocations.getOrNull(frameInd) == null) {
	if (nodeLocations[frameInd] == null) {

+                )
+                Box {
+                  Box(

Improve visualizer usability #1382

Are you sure you want to change the base?

Improve visualizer usability #1382

Uh oh!

Conversation

wenli-cai commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wenli-cai Jul 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wenli-cai Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

steve-the-edwards left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wenli-cai commented Jul 24, 2025 •

edited

Loading

wenli-cai Jul 26, 2025 •

edited

Loading

wenli-cai Aug 15, 2025 •

edited

Loading